<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Eclipse Platform/Core</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="http://dev.eclipse.org/default_style.css" type="text/css">
</head>
<body>
<center>
	<font class=indextop>core</font><br>
	<font class=indexsub>the foundation of the platform</font><p></p>
	<a href="../../main.html">[home]</a>
	<a href="../../documents.html">[documents]</a>
	<a href="../../downloads.html">[downloads]</a>
	<a href="../../resources.html">[resources]</a>
	<a href="../../planning.html">[planning]</a>
	<a href="../../testing.html">[testing]</a>
</center>
<br>

<table BORDER=0 CELLPADDING=2 WIDTH="100%" >
	<tr> 
		<td ALIGN=LEFT VALIGN=TOP COLSPAN="2" BGCOLOR="#0080C0"><b><font face="Arial,Helvetica" color="#FFFFFF">Gathering Information About Your Plug-in</font></b></td>
	</tr>
<!--	
	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>title</b> 
			<ul>
				<li>item</li>
			</ul>
		  <p>&nbsp;</p>
		</td>
	</tr>
-->

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Why doesn't my plug-in work? (Debugging your plug-in in the Eclipse SDK)</b> 
<p>Sometimes plug-in developers write their plug-ins and test them in the Eclipse 
  environment and everything works fine. But then they export their plug-in and 
  try to run it in an Eclipse build and its not there. Here are a few debugging 
  tips for plug-in developers to help them figure out what is going on within 
  the Eclipse system. These tips are also handy when supplying Eclipse plug-in 
  developers information in bug reports when you are trying to help them track 
  down problems.</p>
<p><em>Note that this document was written with a win32 system in mind but most 
  items can be applied to other platforms.</em></p>
  <p>&nbsp;</p>
		</td>
	</tr>
	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Where is my Log?</b> 
<p>Eclipse has a log file where problems are recorded and usually this is the 
  first thing that an Eclipse developer asks for when you report a problem. The 
  log file can be found in a couple of places:</p>
<ul>
  <li><em>Workspace log</em> - This is the most common location for the log file, 
    It is stored in your workspace in the meta-data directory. Check out <code>workspace/.metadata/.log</code>.</li>
  <li><em>Configuration log</em> - Sometimes information is recored in the configuration 
    log file instead of the workspace log. (especially if the workspace hasn't 
    been created yet, there isn't one, or it cannot be created) Check your configuration 
    area for a configuration log file. (<code>configuration/&lt;timestamp&gt;.log</code>)</li>
  <li><em>Startup</em> - Occasionally problems happen in the system really early 
    before there is a workspace and before there is a configuration area. This 
    means that there is nowhere to write the log file so information is written 
    to the console, See the notes below on running with a console to get these 
    messages.</li>
</ul>
<p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Know your VM</b> 
<p>When you double-click on the Eclipse icon, the Eclipse executable searches 
  your path and runs the first Java executable that it finds. This can be problematic 
  people aren't always aware of what they have installed. Sometimes multiple Java 
  VMs may be on your path but an older version may appear first so that is the 
  one that is being used to run Eclipse. Its always best to explicitly run with 
  a known vm using the -vm command line argument and specifying the path to the 
  executable.</p>
<blockquote>
  <p><code>eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Use a console</b> 
<p>When you double-click on the Eclipse icon to start Eclipse, by default it runs 
  with <code>javaw.exe</code>. This is nice because there is one less item in 
  your system tray (and hey its all about real estate) but you really need that 
  console if something goes wrong. Therefore we recommend you run Eclipse with 
  the regular <code>java.exe</code> and <em>not</em> the <code>javaw.exe</code>. 
  (use the same command-line as above)</p>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Stack dumps</b> 
<p>If you are running with a console, then you are able to ask the VM for a stack 
  dump of the threads that are currently running. In the console, hit <code>ctrl-break</code> 
  to get this output. This is useful especially in deadlocking scenerios so you 
  can see exactly what is going on.</p>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>OSGi console</b> 
<p>Above when we said &quot;console&quot; we meant DOS console but just so they 
  don't feel left out OSGi has a console too! And it can provide you with lots 
  of useful information. Start Eclipse with the -console command line argument 
  to start the OSGi console. The &quot;<code>ss</code>&quot; command will print 
  out a list of plug-ins in the system and their current state. This is very helpful 
  when trying to debug if your new plug-in is actually being recognized by the 
  system.</p>
<blockquote>
  <p><code>eclipse -console</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Don't Miss Log Entries</b> 
<p>Generally in Eclipse when you get an error, a message and stack trace is logged 
  to your workspace log. This is great but can easily be missed unless you are 
  looking for it. And some plug-ins silently log entries to the log file. Tsk 
  tsk. In order to never miss entries being logged, we use the <code>-consoleLog</code> 
  command-line argument. This basically means &quot;anything you log to the log 
  file should be logged to the console as well&quot;.</p>
<blockquote>
  <p><code>eclipse -consoleLog</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Debug Mode</b> 
<p>Most plug-ins take advantage of the debug options file mechanism that the runtime 
  provides. This means that you can provide a file with a list of key/value pairs 
  of debug options and the appropriate plug-ins will recognize this and print 
  out their debug information. </p>
<p>Most plug-ins which use this mechanism provide a default <code>.options</code> 
  file in their plug-in for users to copy and edit for their debugging purposes. 
  See the example <code>.options</code> files in the <code>org.eclipse.osgi</code> 
  and <code>org.eclipse.core.runtime</code> plug-ins. </p>
<p>With the -debug command line argument you can optionally specify the location 
  of the debug options file to use. If you don't specify one, then it is assumed 
  that the file is named <code>.options</code> and it is found in the same folders 
  as the Eclipse executable.</p>
<p>Even if you use <code>-debug</code> without specifying a file path and no options 
  file exists at the default location, some basic debug information will be displayed.</p>
<p>Note that all debug information is displayed to the console and not to 
  a log file.</p>
<blockquote> 
  <p><code>eclipse -debug</code><br>
  <code>eclipse -debug c:\eclipse\my_profile.debug</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Cleaning My Configuration</b> 
<p>If you are having problems getting the system to pick up your new plug-in, 
  then perhaps your configuration is out of date. This might be the case if you 
  just unzipped a new plug-in into your <code>/plugins</code> directory and started 
  up...Eclipse had parsed and cached the list of plug-ins that were previously 
  in that directory and now it has changed without it recognizing that fact. You 
  can clear any per-configuration cached data by using the <code>-clean</code> 
  command line argument. </p>
<p>Note that <code>-clean</code> flushes the registry caches (amung other information) 
  and forces the plug-in manifests to be parsed in order to regenerate the registry. 
  This is not optimal for everyone all the time because (depending on the size 
  of your development environment) it may take up to a couple of minutes.</p>
<blockquote>
  <p><code>eclipse -clean</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>VM Args</b> 
<p>There are other optional arguments that can be passed along to the VM and these 
  must be put at the end of the command-line. Common arguments to pass are the 
  maximum VM heap size and values for System properties.</p>
<blockquote> 
  <p> <code>eclipse -vmargs -Xmx384M -Dmy.property=true</code></p>
</blockquote>
		  <p>&nbsp;</p>
		</td>
	</tr>

	<tr> 
		<td ALIGN=RIGHT VALIGN=TOP WIDTH="2%"><img SRC="../../images/Adarrow.gif" BORDER=0 height=16 width=16></td>
    	<td WIDTH="98%"><b>Putting it all together</b> 
<p>That's a lot of information and command-line arguments. Here is an example 
  where it is all put together.</p>
<p><code>eclipse -vm c:\jdks\java_1.4.2_06\jre\bin\java.exe -console -consoleLog 
  -debug -vmargs -Xmx384M</code></p>
<p>&nbsp;</p>
		  <p>&nbsp;</p>
		</td>
	</tr>
</table>
</body>
</html>
